feat(wr-agent): Service::Forward, loopback port forwarding over the multiplex (#208, agent half) - #217

Part of #208 (interchangeability services): port forwarding, the agent half. Stacked on #216; merge that first. The app half (a local listener on the Mac that opens one stream per accepted connection) is the next PR.

What this does

A forwarded port becomes another service on the multiplex, as the design doc specifies (docs/designs/remote-workrooms.md, Phase 2 "Port forwarding over the agent's own stream"): no provider public hostname is needed, and it works identically on a local container. It only carries while a client is attached, by construction: every forwarded socket is owned by the multiplex connection that opened it and is closed with it.

• Protocol: Service::Forward = 0x05, PROTOCOL_VERSION 5, MIN_FORWARD_VERSION = 5 checked against the peer's raw Hello.protocol_version (never folded into negotiate), as MIN_FILE_VERSION and MIN_STATUS_VERSION are.
• Wire (wr-agent/src/forward.rs, module doc is the contract): one TCP connection per stream. Every payload is one opcode byte then a body: OPEN (JSON {"method":"open","host":"127.0.0.1","port":N}, deny_unknown_fields), REPLY ({"version":1,"result":{"opened":true}} or {"version":1,"error":{"<kind>":"<detail>"}}), DATA, EOF (half-close), CLOSE. Error kinds unsupported, refused, connect; the fixed detail strings are tabulated in the module doc. A stream id is free again only once the client has seen its CLOSE.
• Target: loopback only, matched as three literals and never resolved: 127.0.0.1, ::1, localhost (both addresses tried). 127.0.0.2, ::ffff:127.0.0.1, 0.0.0.0 and everything else are refused. No reverse forwarding.
• Threading: two threads per forward, pty/file style, no runtime, no new dependency. The connect (3 s bound) runs on the forward's thread, so the connection's envelope reader never blocks on a forward. Client bytes queue on an unbounded channel bounded by a 2 MiB per-forward budget; past it the forward is killed with CLOSE rather than buffered without limit. 64 forwards per connection.
• Closing: peer write-half closed → EOF; both halves done → CLOSE; TCP failure → CLOSE; client EOF → shutdown(Write); client CLOSE → shutdown(Both); multiplex drop → every owned socket shut down. Traffic for an unopened stream, stream 0 and unknown opcodes are dropped silently, as serve.rs drops an unhandled service byte.
• Not OS-gated: builds and tests on macOS, so the app half can be verified in a running app.

Review finding fixed here

The agent-written draft lost a CLOSE, an overflow kill or a connection drop that landed during the 3 s connect window: the thread then registered the fresh socket nowhere, replied opened, and its reader pumped DATA onto a stream id the client had freed and may have re-used. Fixed in 76d9143: the socket is registered under the map lock only if the forward's entry is still there, else shut down on the spot. The unit test fails without the guard.

Validation

• cargo test --manifest-path vcs/Cargo.toml -p wr-agent: after the review 227 pass (20 unit tests in forward.rs, 16 integration tests in tests/forward_service.rs against a real echo server: both-direction round trip including a 1.5 MB multi-envelope payload and a byte-by-byte split, two concurrent forwards do not mix, peer close → EOF then CLOSE, client CLOSE → peer sees EOF, client EOF → peer sees EOF, refused port → error reply, non-loopback refused, multiplex drop closes sockets, a second connection's forward survives the first's departure, already-forwarding refusal leaves the healthy forward alone, stray traffic dropped).
• cargo fmt --check clean; cargo clippy --workspace --all-targets -- -D warnings clean.
• Pty tests fail inside the command sandbox (forkpty: Operation not permitted); pre-existing, unrelated; all runs above with the sandbox off.

Not in this PR

• The app half: MIN_FORWARD_VERSION on the Swift side (AgentControlClient.swift), a local listener, and a way to ask for a port. Next PR.
• A deterministic test of a genuinely stalled TCP peer (kernel buffer auto-tuning makes it nondeterministic); the overflow branch is covered as a unit test with a hand-registered forward instead.
• Per-stream flow control on the multiplex (a credited window). The per-forward byte budget is the stated ceiling.
• Pre-existing Linux-only unused-import warning at wr-agent/src/file.rs:33, left alone.

Independent review (2026-09-22)

Per macapp/AGENTS.md rule 3. gstack /review: testing, security and maintainability specialists, two Claude adversarial passes and two Codex adversarial passes plus a Codex structured review. Fix commit: cf3dfcf9.

The finding every source converged on: the token guarded the map, not the wire. A failed connect, a failed clone, the budget kill and the client's own CLOSE each wrote REPLY/CLOSE on a stream the client may already have freed, and the shutdown a close performs made the socket reader send an EOF for it (read returns Ok(0) for a shutdown exactly as for a peer's half-close). The shipped Swift client fails its whole agent connection on a stray envelope, so a straggler on a re-used id took VCS, files and status down with it. And a client's own CLOSE was never answered, so the documented rule ("free once you have seen CLOSE") could not be kept.

Fixed: every terminal emission comes from the forward's own threads. A kill (client CLOSE, the budget, a reset seen by the reader) marks the forward, wakes both threads and shuts the socket; the last thread out forgets the stream and sends the one CLOSE, after any DATA or EOF; nothing else writes CLOSE. So a client CLOSE is answered, a reset no longer strands the writer on the channel (it held the slot until the client noticed), and a CLOSE that lands during the connect gets CLOSE alone. Also: an OPEN on a live stream is refused before its body is parsed (a malformed duplicate used to send CLOSE for a healthy forward the agent kept running); the 64 cap counts threads alive, not map entries (failing connects held no slot); empty DATA and a second EOF cost the budget (they were free channel nodes behind a stalled write); DATA after the client's EOF is dropped, not charged (it was, and killed a healthy forward mid-reply); a refused host is abbreviated and send refuses an over-cap payload (a maximum-sized OPEN produced a reply larger than an envelope, and Envelope::encode asserted under the shared writer lock); both socket clones must succeed (a failed shutdown handle was a forward nothing could end); the connect deadline spans both localhost addresses (it was 3 s each); the doc's error table gains the clone-failure row. Tests: 17 unit (9 before), 15 integration (11 before), including CLOSE-is-last after a budget kill, a peer reset, a client CLOSE answered, localhost reaching a ::1-only server.

Accepted, with the reason:

• OPEN refusals are written on the connection's dispatch thread, under the shared writer, as every other service's error replies are. Bounded by the transport's write timeout.
• A partial envelope write after the 10 s write timeout leaves the multiplex misaligned for the connection's remaining life. Pre-existing for every service (vcs::send, pty output); the connection is dead at that point in practice. Candidate for a TODO on the transport, not this PR.
• The reader thread of a forward whose peer never sends and whose client never closes is parked for the connection's life. By design: it is the forward.
• For the app half (feat(macapp): forward a loopback port over the agent multiplex (#208, app half) #218): the Swift receive() guards must admit service 5 and its opcodes 0x02–0x05 (today both the service check and the chunk-marker check would fail the connection), and a client must wait for CLOSE before re-using an id.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GhhmRhjiSBmajC7LrFUxGV

Summary by CodeRabbit

• New Features

  • Added agent-side TCP port forwarding to services running on the local machine.
  • Supports IPv4 loopback, IPv6 loopback, and localhost, with bidirectional data transfer and graceful half-close.
  • Supports up to 64 simultaneous forwards per connection; forwards close when the client detaches or the connection ends.

• Limitations

  • Forwarding to remote hosts and app client/UI support are not yet available.
  • Connections that cannot be established within three seconds or exceed data limits are closed.